home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / poll.z / poll
Encoding:
Text File  |  1998-10-20  |  8.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. PPPPOOOOLLLLLLLL((((2222))))                                                                PPPPOOOOLLLLLLLL((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      poll - input/output multiplexing
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttrrrrooooppppttttssss....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppoooollllllll....hhhh>>>>
  14.  
  15.      iiiinnnntttt ppppoooollllllll((((ssssttttrrrruuuucccctttt ppppoooollllllllffffdddd ****ffffddddssss,,,, uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg nnnnffffddddssss,,,, iiiinnnntttt ttttiiiimmmmeeeeoooouuuutttt))));;;;
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      The IRIX version of _p_o_l_l provides users with a mechanism for multiplexing
  19.      input and output over a set of any type of file descriptors, rather than
  20.      the traditional limitation to only descriptors of STREAMS devices [see
  21.      _s_e_l_e_c_t(2)].  _P_o_l_l identifies those descriptors on which a user can send
  22.      or receive messages, or on which certain events have occurred.
  23.  
  24.      _F_d_s specifies the file descriptors to be examined and the events of
  25.      interest for each file descriptor.  It is a pointer to an array with one
  26.      element for each open file descriptor of interest.  The array's elements
  27.      are _p_o_l_l_f_d structures which contain the following members:
  28.  
  29.           int fd;             /* file descriptor  */
  30.           short events;       /* requested events */
  31.           short revents;      /* returned events  */
  32.  
  33.      where _f_d specifies an open file descriptor and _e_v_e_n_t_s and _r_e_v_e_n_t_s are
  34.      bitmasks constructed by or-ing any combination of the following event
  35.      flags:
  36.  
  37.      POLLIN         Data other than high priority data may be read without
  38.                     blocking.  For STREAMS, the flag is set even if the
  39.                     message is of zero  length.
  40.  
  41.      POLLRDNORM     Normal data (priority band = 0) may be read without
  42.                     blocking.  For STREAMS, the flag is set even if the
  43.                     message is of zero  length.
  44.  
  45.      POLLRDBAND     Data from a non-zero priority band may be read without
  46.                     blocking.  For STREAMS, the flag is set even if the
  47.                     message is of zero  length.
  48.  
  49.      POLLPRI        High priority data may be received without blocking.  For
  50.                     STREAMS, this flag is set even if the message is of zero
  51.                     length.
  52.  
  53.      POLLOUT        Normal data may be written without blocking.
  54.  
  55.      POLLWRNORM     The same as POLLOUT.
  56.  
  57.      POLLWRBAND     Priority data (priority band > 0) may be written. This
  58.                     event only examines bands that have been written to at
  59.                     least once.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPOOOOLLLLLLLL((((2222))))                                                                PPPPOOOOLLLLLLLL((((2222))))
  71.  
  72.  
  73.  
  74.      POLLERR        An error message has arrived at the _s_t_r_e_a_m _h_e_a_d.  This
  75.                     flag is only valid in the _r_e_v_e_n_t_s bitmask; it is not used
  76.                     in the _e_v_e_n_t_s field.
  77.  
  78.      POLLHUP        A hangup has occurred on the _s_t_r_e_a_m.  This event and
  79.                     POLLOUT are mutually exclusive; a _s_t_r_e_a_m can never be
  80.                     writable if a hangup has occurred.  However, this event
  81.                     and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not
  82.                     mutually exclusive.  This flag is only valid in the
  83.                     _r_e_v_e_n_t_s bitmask; it is not used in the _e_v_e_n_t_s field.
  84.  
  85.      POLLNVAL       The specified _f_d value does not belong to an open _s_t_r_e_a_m.
  86.                     This flag is only valid in the _r_e_v_e_n_t_s field; it is not
  87.                     used in the _e_v_e_n_t_s field.
  88.  
  89.      For each element of the array pointed to by _f_d_s, _p_o_l_l examines the given
  90.      file descriptor for the event(s) specified in _e_v_e_n_t_s.  The number of file
  91.      descriptors to be examined is specified by _n_f_d_s.  If _n_f_d_s exceeds
  92.      NOFILES, the system limit of open files [see _u_l_i_m_i_t(2)], _p_o_l_l will fail.
  93.  
  94.      If the value _f_d is less than zero, _e_v_e_n_t_s is ignored and _r_e_v_e_n_t_s is set
  95.      to 0 in that entry on return from _p_o_l_l.
  96.  
  97.      The results of the _p_o_l_l query are stored in the _r_e_v_e_n_t_s field in the
  98.      _p_o_l_l_f_d structure.  Bits are set in the _r_e_v_e_n_t_s bitmask to indicate which
  99.      of the requested events are true.  If none are true, none of the
  100.      specified bits is set in _r_e_v_e_n_t_s when the _p_o_l_l call returns.  The event
  101.      flags POLLHUP, POLLERR and POLLNVAL are always set in _r_e_v_e_n_t_s if the
  102.      conditions they indicate are true; this occurs even though these flags
  103.      were not present in _e_v_e_n_t_s.
  104.  
  105.      If none of the defined events have occurred on any selected file
  106.      descriptor, _p_o_l_l waits at least _t_i_m_e_o_u_t msec for an event to occur on any
  107.      of the selected file descriptors.  On a computer where millisecond timing
  108.      accuracy is not available, _t_i_m_e_o_u_t is rounded up to the nearest legal
  109.      value available on that system.  If the value _t_i_m_e_o_u_t is 0, _p_o_l_l returns
  110.      immediately.  If the value of _t_i_m_e_o_u_t is -1, _p_o_l_l blocks until a
  111.      requested event occurs or until the call is interrupted.  _p_o_l_l is not
  112.      affected by the O_NDELAY and O_NONBLOCK flag.
  113.  
  114.      _p_o_l_l fails if one or more of the following are true:
  115.  
  116.      [EAGAIN]     Allocation of internal data structures failed but request
  117.                   should be attempted again.
  118.  
  119.      [EFAULT]     Some argument points outside the allocated address space.
  120.  
  121.      [EINTR]      A signal was caught during the _p_o_l_l system call.
  122.  
  123.      [EINVAL]     The argument _n_f_d_s is less than zero, or _n_f_d_s is greater than
  124.                   NOFILES.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPOOOOLLLLLLLL((((2222))))                                                                PPPPOOOOLLLLLLLL((((2222))))
  137.  
  138.  
  139.  
  140. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  141.      intro(2), select(2), read(2), write(2), getmsg(2), putmsg(2), streamio(7)
  142.  
  143. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  144.      Upon successful completion, a non-negative value is returned.  A positive
  145.      value indicates the total number of file descriptors that has been
  146.      selected (i.e., file descriptors for which the _r_e_v_e_n_t_s field is non-
  147.      zero).  A value of 0 indicates that the call timed out and no file
  148.      descriptors have been selected.  Upon failure, a value of -1 is returned
  149.      and _e_r_r_n_o is set to indicate the error.
  150.  
  151.  
  152. NNNNOOOOTTTTEEEESSSS
  153.      Some devices do not support polling via the _s_e_l_e_c_t(2) and _p_o_l_l(2) system
  154.      calls.  Doing a _s_e_l_e_c_t or _p_o_l_l on a file descriptor associated with an
  155.      "un-pollable" device will cause the _s_e_l_e_c_t or _p_o_l_l to return immediately
  156.      with a success value of 0 and the with the corresponding file descriptor
  157.      events of queried set true.  For instance, if a _s_e_l_e_c_t or _p_o_l_l is
  158.      performed on a read file descriptor associated with an un-pollable
  159.      device, the call would return immediately, even though there may be
  160.      nothing to read on the device.  A subsequent _r_e_a_d(2) in this situation
  161.      might return with a "bytes-read" count of 0 or might block if the device
  162.      supports read blocking.  Devices which exhibit this behavior (especially
  163.      those from third-party vendors) should be suspected as not supporting
  164.      polling.
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.